home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / c / asmlib35.zip / SOURCE.DOC < prev    next >
Text File  |  1993-01-09  |  11KB  |  298 lines
  1. SOURCE.DOC Copyright (C) 1992, 1993 Douglas Herr ■ all rights reserved
  2.  
  3. ASMLIB uses a number of subroutines which are not applicable to general
  4. programming.  These subroutines include "$" in their names.  All "$"
  5. subroutines require a near call, so the calling program must be in the same
  6. segment as the called subroutine.  The segment names used by ASMLIB are:
  7.  
  8. asmtiny: _TEXT  (assumes CS:DGROUP, DS:DGROUP)
  9. asmsmall: _TEXT (assumes CS:_TEXT, DS:DGROUP)
  10. asmlib: _MEDIUM (assumes CS:_MEDIUM, DS:DGROUP)
  11. asmhuge: _HUGE  (assumes CS:_HUGE, DS:DGROUP)
  12.  
  13.  
  14. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  15.  
  16. $emspage:    position logical EMS page at page frame
  17. source:      $emspage.asm
  18.  
  19. Call with:   DS:[BX] pointing to 4-byte offset into allocated EMS block
  20.              DX = EMS handle
  21. Returns:     if CF = 0, no error
  22.              if CF = 1, AH = error code
  23. Uses:        AX, flags
  24.  
  25. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  26.  
  27. $fget:       read more data into file buffer
  28. Source:      $fget.asm
  29.  
  30. Call with:   BX = file handle
  31.              ES = buffer segment address
  32. Returns:     if CF = 1, AX = DOS error code
  33. Uses:        AX, DX, SI, DS, flags
  34.  
  35. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  36.  
  37. $handle:     verify handle for buffered file I/O
  38. Source:      fopen.asm
  39.  
  40. Call with:   BX = file handle
  41.              ASSUMES DS:DGROUP
  42. Returns:     if CF = 0, SI points to file handle in ASMLIB buffer data area
  43.                         segment address of buffer associated with this handle
  44.                         at 2[SI]
  45.              if CF = 1, handle in BX not managed by ASMLIB buffer system
  46. Uses:        SI, flags
  47.  
  48. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  49.  
  50. a$putw:      module used by several ASMLIB text subroutines to copy
  51.              a character/attribute pair to a window of the screen;
  52.              includes snow control logic for CGA systems.
  53. Source:      a$putw.asm
  54.  
  55. Call with:   CX = column width of window
  56.              DX = 0 to disable snow control
  57.                 = 3DAh to enable snow control
  58.              SI = row height of window
  59.              ES:[DI] points to video buffer
  60.              AL = character
  61.              AH = color attribute
  62.              BX = bytes per screen row (80-column screen has 160 bytes per row)
  63.              DF = 0 (clear direction flag with CLD)
  64. Uses:        DI, SI, flags
  65.  
  66.  
  67. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  68.  
  69. a$paint:     used to change color of the screen; used by Paint and
  70.              WPaint subroutines.  Includes snow control logic for CGA
  71.              systems.
  72. Source:      a$paint.asm
  73.  
  74.  
  75.  
  76. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  77.  
  78. a$recolor:   used to change color of the screen; used by ReColor and
  79.              WReColor subroutines.  Includes snow control logic for CGA
  80.              systems.
  81. Source:      a$recolor.asm
  82.  
  83.  
  84. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  85.  
  86. a$wdata:     parameter manager for ASMLIB's Window subroutines.
  87. Source:      a$wdata.asm (crtinfo.asm)
  88.  
  89.              Detailed parameter requirements and output listed in
  90.              source code; do not call this subroutine unless you know
  91.              what you're doing.
  92.  
  93.  
  94. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  95.  
  96. $gpick:      select string from fixed-field string block; graph mode
  97. source:      $gpick.asm (heap.asm, strncpy.asm, drawbox.asm, fillbox.asm,
  98.                gprint.asm, dosalloc.asm, bitblock.asm, bbbytes.asm,
  99.                strlen.asm, gcolor.asm, a$menu.asm, $graph.asm, m$input.asm,
  100.                v$extkey.asm, m$chrn.asm, m$nkey.asm)
  101.  
  102. call with:   ES = segment address of string list
  103.              AX = number of strings
  104.              CX = field size
  105.              BX = initial choice
  106.              DS:[DX] pointing to initial coordinates
  107.              assumes DS:DGROUP
  108. returns:     AX = returning keycode
  109.              BX = returned selection number
  110. uses:        AX, BX, CX, DX, SI, DI, flags
  111.  
  112. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  113.  
  114. $herc:       detects Hercules-compatible equipment; does not determine
  115.              if Hercules equipment is the default monitor (see IsHerc)
  116. Source:      $herc.asm
  117.  
  118. Call with:   no parameters; NEAR CALL REQUIRED
  119. Returns:     if CF = 1, no Hercules-compatible equipment installed
  120.              if CF = 0, AX = Hercules model
  121.                        128 = Hercules Graphics Card or compatible
  122.                        144 = Hercules Graphics Card Plus
  123.                        208 = Hercules InColor card
  124. Uses:        AX, flags
  125.  
  126.  
  127. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  128.  
  129. $strstr:     string search module used by several ASMLIB subroutines
  130. Source:      $strstr.asm
  131.  
  132. Call with:   ES:[DI] -> search string, DS:[SI] -> substring
  133.              BX = substring length, DX = search string length
  134.              NEAR CALL REQUIRED
  135. Returns:     CF = 1, AX = -1 if no match
  136.              AX = match offset
  137. Uses:        AX, BX, CX, DX, SI, DI, flags
  138.  
  139.  
  140.  
  141. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  142.  
  143. $wcopy:      copies word data from one portion of memory to another;
  144.              includes snow control logic for CGA systems.
  145. Source:      $wcopy.asm
  146.  
  147. Call with:   CX = words to copy
  148.              DS:[SI] -> source
  149.              ES:[DI] -> destination
  150.              DX = CRTC status port if CGA, else 0
  151.              DF = 0 or 1
  152. Returns:     ES:[DI] pointing past end of destination
  153.              DS:[SI] pointing past end of block
  154.              CX = 0
  155. Uses:        AX, CX, DI, SI, flags
  156. Called by:   WSave, WRestore, GetScreen, PutScreen, TCopy, VScroll, HScroll
  157.  
  158.  
  159. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  160.  
  161. m$putwindow:  save screen, clear window & print window frame
  162. Source:       m$putw.asm (wsize.asm, wsave.asm, dosalloc.asm, wframe.asm,
  163.                           wclear.asm)
  164.  
  165. Call with:    DS:[BX] pointing to window corner data
  166. Returns:      ES = segment address of saved screen area
  167. Uses:         ES, flags
  168. Called by:    PICKSTR
  169.  
  170.  
  171. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  172.  
  173. $strlist:     copy group of ASCIIZ strings to block of fixed-length strings
  174. source:       $strlist.asm (dosalloc.asm, strlen.asm, m$count.asm)
  175.  
  176. Call with:    DS:[SI] pointing to first string to copy
  177.               string group terminated with double NUL
  178.               requires sufficient free DOS memory
  179.  
  180. Returns:      if CF = 1, insufficient DOS memory available
  181.               if CF = 0:
  182.                ES = base segment address of string block
  183.                AX = number of strings
  184.                CX = string field size
  185. Uses:         AX, CX, ES, flags
  186. Called by:    PICKSTR, GPICKSTR
  187.  
  188.  
  189. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  190.  
  191. m$count:      counts a group of ASCIIZ strings
  192. Source:       m$count.asm (strlen.asm)
  193.  
  194. Call with:    DS:[BX] pointing to first string
  195.               string group terminated with double NUL
  196. Returns:      AX = number of strings
  197.               CX = length of longest string counted
  198. Uses:         AX, BX, CX, flags
  199. Called by:    PICKSTR, PULLDOWN
  200.  
  201.  
  202. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  203.  
  204. m$nkey:       process normal keystroke for menu subroutines
  205. Source:       m$nkey.asm (isupper.asm, m$chr.asm)
  206.  
  207. Call with:    AL = key code
  208.               BX = initial cursor position
  209.               CX = field width
  210.               DX = number of menu choices
  211.               ES:[DI] pointing to first menu choice
  212. Returns:      BX = output position
  213.                if CF = 0, found matching character
  214.                if CF = 1, no match
  215. Uses:         AX, BX, CX, DX, DI, flags
  216. Called by:    $pick
  217.  
  218.  
  219. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  220.  
  221. m$chr:        determines if a keycode is the first uppercase character
  222.               in a string
  223. Source:       m$chr.asm (strlen.asm)
  224.  
  225. Call with:    AX = keycode
  226.               DS:[BX] pointing to string
  227. Returns:      if CF = 1, string length = 0
  228.               if CF = 0:
  229.                 CX = 0 if no upper case characters in the string
  230.                 if CX <> 0, AH = first UCASE character
  231.                 ZF = 1 if character is first ucase in string
  232.                 DS:[BX] points to first ucase character
  233. Uses:         AX, BX, CX, flags
  234. Called by:    $pick, PULLDOWN
  235.  
  236.  
  237. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  238.  
  239. $listwindow:  calculates window dimensions for input list; adjusts
  240.               upper left corner coordinates if required to fit on screen
  241. Source:       $listw.asm (crtinfo.asm)
  242.  
  243. Call with:    DS:[BX] pointing to 8-byte data area for window corner data
  244.               AX = number of choices in list
  245.               CX = list field width
  246.               DH = desired first screen row for list
  247.               DL = desired first column for list
  248.               $listwindow assumes that DH < total screen rows
  249. Returns:      DH = adjusted first row for $pick
  250.               DL = adjusted first column for $pick
  251.               8 bytes at DS:[BX] are updated with window corner coordinates
  252.               for WSave, WFrame, WRestore, etc.
  253. Uses:         DX; all other registers and flags are saved
  254. Called by:    PICKSTR, PICKFILE
  255.  
  256.  
  257. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  258.  
  259. $pick:        select one string from a list of fixed-length strings
  260. Source:       $pick.asm (crtinfo.asm, str2vbuf.asm, a$putw.asm, m$input.asm,
  261.                          m$chr.asm, m$nkey.asm, a$menu.asm, v$extkey.asm))
  262.  
  263. Call with:    ES:[DI] pointing to list of choices
  264.               AX = number of menu choices
  265.               CX = field width
  266.               BX = initial cursor position
  267.               DH = top screen row
  268.               DL = left screen column
  269.               Returns to calling program when Esc, Enter or ^C pressed
  270.  
  271. Returns:      if BreakTrap enabled:
  272.                if CF = 1, ^C or ^Break was pressed
  273.               AX = last key pressed (AX = 3 if ^C pressed)
  274.               BX = string number selected (first string = 0)
  275. Uses:         AX, BX, CF
  276. Called by:    PICKSTR, PICKFILE
  277.  
  278. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  279.  
  280. v$extkey:     extended keycode processor for ASMLIB vertical list menus
  281.               (text and graph modes)
  282. Source:       v$extkey.asm
  283.  
  284. Call with:    AL = low word of ASMLIB extended key code
  285.               [bp-2] = field width of string list
  286.               [bp-4] = number of choices
  287.               [bp-6] = current choice
  288.               [bp-8] = first string to print (for scrolling if required)
  289.               [bp-10] = number of strings to print 
  290.                         ( = number of choices if no scrolling required)
  291.  
  292. Returns:      if CF = 0, modifies [bp-6] and [bp-8]
  293.               if CF = 1, keycode not a valid cursor movement key
  294.               valid keys: Up, Down, Home, End, PgUp, PgDown
  295.  
  296. Uses:         AX, flags
  297. Called by:    $pick, $gpick
  298.